draft: UTXO reservation wallet-side foundations - #4238

## Summary

Extends PR #4238 (proposal structs, marshaling, chain-interface stubs —
no executor) with the missing pieces: real ABI bindings for the
`ReservationRouter`, chain-interface implementations against those
bindings, the acceptance and re-anchor executors (proposal generation +
SPV proof submission), three monitoring watchers (stranding,
stale-deposit, action-timeout), and operator wiring gated behind
`config.Reservations.Enabled`.

**Repo:** threshold-network/keep-core
**Branch:** m1/keep-core-client
**Base:** reservations-epic
**Diffstat (this PR vs reservations-epic, working tree):** 84 files
changed, 25818 insertions(+), 72 deletions(-)

## Build pipeline (serial gates, parallel middle)

Ten commits, four sequential stages — later stages depend on earlier
ones' output, so this was not built as one flat diff:

1. `277865cb4` — regenerate Go ABI bindings for the reservation router
surface (`abi/gen`, `cmd/gen`, `contract/gen` — `ReservationRouter.go`
files, ~9,800 lines total across the three layers; plus incremental
diffs to
`Bridge.go`/`RedemptionWatchtower.go`/$WalletProposalValidator.go` for
the reservation-adjacent methods those contracts already exposed).
2. `e49e954e8` — reservation read/validate methods against the real
bindings, on `pkg/tbtc.Chain`.
3. `4ba2f2267` (`CurrentMonkey`) — reservation write methods, remaining
views, event subscriptions on `pkg/tbtc.Chain`.
4. `053577925` (gate 2.5, manager-run — narrow mechanical scope, not
delegated) — extends the same reservation methods onto
`pkg/tbtcpg.Chain` and `pkg/maintainer/spv.Chain`. This gate caught and
fixed a real defect first — see below.
5. Three genuinely independent builders, each its own worktree/branch
off `053577925`, then merged sequentially:
- `e37211b33` (`AcceptanceBuilder`) —
`pkg/tbtcpg/reservation_acceptance.go` (candidate selection + proposal
assembly) + `pkg/maintainer/spv/reservation_acceptance_proof.go` (SPV
proof submission).
   - `603ad0d54` (`ReanchorBuilder`) — the re-anchor equivalents.
- `ac58650a1` (`WatchersBuilder`) —
`pkg/maintainer/spv/reservation_{stranding,stale_deposit,action_timeout}_watch.go`.
- Merges: `2bd8731ce` (acceptance, clean), `daeb6afaf` (re-anchor,
clean), `c29de0b8f` (watchers — one real conflict, see below).
6. `48985451d` (`HilariousTermite`, serial operator wiring) — registers
both proposal tasks in `pkg/tbtcpg/tbtcpg.go`, both proof tasks in
`pkg/maintainer/spv/spv.go`, and the three watcher event subscriptions
in `pkg/tbtc/tbtc.go`, all gated behind `config.Reservations.Enabled`.
7. `b14a38851` — merge: pull in reservations-epic base updates
(bitcoin.Chain context-aware confirmation lookups) to fix local build
breakage.

## What ships (current state)

| Area | Files | Content |
|---|---|---|
| ABI bindings (generated) |
pkg/chain/ethereum/tbtc/gen/{abi,cmd,contract}/ReservationRouter.go +
incremental diffs to Bridge.go, RedemptionWatchtower.go,
WalletProposalValidator.go, LightRelay*.go | ~9,800 new lines, generated
from the ABI, not hand-written |
| Chain interface | pkg/chain/ethereum/tbtc.go (+1479),
pkg/tbtc/chain.go (+495/-…), pkg/tbtcpg/chain.go (+124),
pkg/maintainer/spv/chain.go (+111) | Read/write/event methods against
the real router surface. All reservation reads/writes/event
subscriptions target the **Bridge** address via fallback delegatecall,
never the router's own deployed address (see PR G's invariant note) |
| Coordination dispatch | pkg/tbtc/node_coordination.go (+18),
pkg/tbtc/node_proposals.go (+128), pkg/tbtc/coordination.go (+27) |
Wires agreed ActionReservationAnchor/ActionReservationReanchor proposals
to handleReservationAnchorProposal/handleReservationReanchorProposal,
which assemble, sign, and broadcast the anchor/re-anchor Bitcoin
transaction; checklist gating uses a chain-derived activation block, not
local config alone |
| Wallet action assembly | pkg/tbtc/reservation.go (+1032) |
assembleReservationAnchorTransaction/assembleReservationReanchorTransaction
and the wallet action types the dispatch above invokes |
| Acceptance executor | pkg/tbtcpg/reservation_acceptance.go (+714) |
ReservationAcceptanceTask — candidate selection, eligibility checks,
proposal assembly |
| Re-anchor executor | pkg/tbtcpg/reservation_reanchor.go (+472) |
Re-anchor proposal generation |
| SPV proof submission |
pkg/maintainer/spv/reservation_acceptance_proof.go (+109),
reservation_reanchor_proof.go (+312), reservation_proof_loop.go (+505) |
Builds and submits the SPV proof for each proposal type; the proof loop
is the driver that scans wallet transaction history and dispatches to
both submit functions |
| Watchers | pkg/maintainer/spv/reservation_stranding_watch.go (+106),
reservation_stale_deposit_watch.go (+299),
reservation_action_timeout_watch.go (+422) | Permissionless monitoring —
notify stranded/stale/timed-out reservations |
| Operator wiring | pkg/tbtcpg/tbtcpg.go (+24/-…),
pkg/maintainer/spv/spv.go (+12),
pkg/maintainer/spv/reservation_wiring.go (+417), pkg/tbtc/tbtc.go
(+42/-…), pkg/maintainer/spv/config.go (+23), cmd/start.go (+29/-…) |
Task/proof registration and event-subscription wiring, all behind
config.Reservations.Enabled |
| Metrics | pkg/clientinfo/performance.go (+61) | Reservation
action-type metric names, gated so a non-reservation deployment's
registered metric surface is unchanged |
| Tests | pkg/tbtc/{reservation,coordination,chain}_test.go,
pkg/tbtcpg/{reservation_acceptance,reservation_reanchor,chain,tbtcpg,fee,bitcoin_chain}_test.go,
pkg/maintainer/spv/{chain,reservation_acceptance_proof,reservation_proof_loop,reservation_wiring,reservation_action_timeout_watch,reservation_reanchor_proof,reservation_stale_deposit_watch,reservation_stranding_watch}_test.go,
pkg/chain/ethereum/tbtc_test.go,
pkg/tbtcpg/internal/test/{marshaling,reservation_acceptance,tbtcpgtest}.go,
16 JSON test-scenario fixtures, config/config_test.go +
test/config.{json,toml,yaml} | Unit coverage for every new production
file above, including the pure helpers in the SPV proof loop and wiring
layer |

## Two real bugs found and fixed mid-build

1. **Pointer-identity map-key bug** (`AcceptanceBuilder`’s output): the
test-double `reservationAcceptanceLocalChain.reservedDeposits` field was
typed `map[*big.Int]bool`. Go compares `*big.Int` map keys by pointer
identity, not value, so `IsReservedDeposit` always missed even deposits
the test had explicitly marked reserved, because `BuildDepositKey`
allocates a fresh pointer on every call. Fixed by re-keying on
`depositKey.Text(16)` (string).
2. **Zero-output funding-transaction stub**: the happy-path and
bounded-lookback test fixtures stubbed the funding Bitcoin transaction
as `&bitcoin.Transaction{}` (zero outputs), but
`ReservationAcceptanceTask.Run` genuinely calls
`assembleReservationAnchorTransaction`, which reads the funding output's
locking script to validate P2SH/P2WSH — so it panicked with "output
index out of range", then "not P2SH/P2WSH" once the first fix landed.
Fixed by giving the stub transactions a real single P2WSH output
(`0x0020` + 32 zero bytes) and adding the missing `ReservationTxMaxFee`
to the bounded-lookback scenario's `ReservationParameters` (was
defaulting to `0`, so any nonzero anchor fee tripped the "exceeds
configured max" guard).

## Defects caught during the build (both fixed, neither shipped)

- **Gate 2.5 subagent transiently malformed pkg/tbtc/chain.go** while
probing interface satisfaction (duplicate `ReservationChain` block,
methods declared after the interface's closing brace) and deleted the
tracked root main.go, then yielded a PARTIAL_COMPLETION reporting a
bogus SPV build failure it could not explain. Root-caused by the
manager: pkg/tbtc/chain.go was already clean at yield time; the main.go
deletion was the only lasting damage, restored via `git restore
--source=HEAD -- main.go`. The two interface extensions the subagent
actually delivered (pkg/tbtcpg/chain.go +137,
pkg/maintainer/spv/chain.go +97) were structurally correct; the
test-double mocks were missing three Past*Events stub methods, added by
hand. Committed clean…
- **Watchers merge conflict** (c29de0b, in
pkg/maintainer/spv/chain_test.go): two independently-built reservation
test-double representations — [16]byte/[24]byte-keyed maps from the
acceptance/re-anchor lineage vs map[string]-keyed maps re-added by the
watchers branch — plus a duplicate setReservation/setReservationAction
method pair and a dropped submitReservationProofHook field, all caught
and restored during resolution.
- **Build-brief self-correction before dispatch**: the initial build
brief recommended binding a separate read-only "router" handle to the
ReservationRouter's own deployed address for views/events. Verified
wrong against ReservationRouter.sol:71-76 invariant 3 ("NO STANDALONE
AUTHORITY") before any downstream subagent used it — the router's own
address has empty storage, so direct reads return garbage and every
event it emits carries the Bridge's address in the log, not the
router's. Fixed in the persisted brief before the bindings subagent
committed; a localChain unit-test mock would not have caught this since
it doesn't model per-address log-emitter semantics.

## Verification

- ✅ go build ./... — clean
- ✅ go test ./pkg/tbtc/... ./pkg/tbtcpg/... ./pkg/maintainer/spv/...
./pkg/clientinfo/... ./pkg/chain/ethereum/... -v — 340 passed, 0 failed
- ✅ go test ./... — full repo suite, 0 failed
- ✅ go vet ./... — clean except one pre-existing, unrelated issue at
pkg/tecdsa/signing/protocol.go:737 (not touched by this PR)
- ✅ gofmt -l (all changed files) — empty (no formatting issues)

## Review notes

- All reservation reads/writes/event subscriptions target the Bridge
address, never the router's own deployed address — this is a hard
invariant (ReservationRouter.sol:71-76), not a style choice. A reviewer
checking the chain-interface implementation should confirm every
reservation call site uses the bridge handle.
- Config-gated: every new task/proof/watcher registration is behind
config.Reservations.Enabled; with it unset (the default), this PR
changes no runtime behavior for existing (non-reservation) flows.
- The coordination checklist gate additionally requires a chain-derived
ReservationsActivationBlock alongside the local config flag, so a
mixed-rollout signing group (one operator flag-on, another flag-off)
can't cause a flag-off follower to fault an honest flag-on leader.
- No behavioral changes to non-reservation code paths — the diff is
additive except for the Chain interface files, coordination dispatch,
and operator-wiring files, which only add reservation-specific branches.
- Known scope limits, called out as an open follow-up rather than
blocking this PR:
- The action-timeout watcher's wallet-members resolver
(pkg/maintainer/spv/reservation_wiring.go) is a stub that always errors
"wallet members resolver not wired," so CheckReservationActionTimeouts
never reaches its notification path yet; the stranding and stale-deposit
watchers are fully live. Tracked to implement against GetOperatorID once
the on-chain accessor path is confirmed, mirroring
pkg/tbtc/inactivity.go's operator walk.
- ReservedRedemptionProposal/ReservationDissolutionProposal
marshal/assembly scaffolding in pkg/tbtc/reservation.go ships but is
inert for m1 (validator stubs explicitly error "not exposed on the m1
bridge-integration surface"); m1 only activates Acceptance/Reanchor.
Kept in this PR rather than split out since it shares the same
wire-format contract and is fully tested as shipped.
- ReservationAcceptanceTask keeps its stateful incremental-scan cache
(scanState, lastScannedBlock, pendingCandidates) rather than the
review-suggested redesign to a stateless full-rescan matching
DepositSweepTask/RedemptionTask. The confirmed correctness bug the cache
caused (candidates lost across calls) is fixed in this PR; dropping the
cache entirely is a larger architectural change with its own RPC-cost
tradeoff and is deferred to a follow-up rather than bundled into this
fix.